Advanced Collection Management

Table of Contents

1. Overview
- 1.1. Guest Collections and Manager Privileges
2. Document Types
3. Common Query Parameters
4. Common Errors
5. Path Arguments
6. Operations

1. Overview

The advanced collection management resources are available to Globus subscribers. These resources allow users with the appropriate effective roles to view, pause, or cancel tasks on the collections they manage. All operations listed below require the user to have either the "activity_manager" or "activity_monitor" roles on a collection, and the collection must be subscribed. In particular, for TRANSFER tasks the user must have either of the roles on either the source or destination collection to view the task and the manager role to cancel or pause the task. Note that the "activity_manager" role includes all privileges of the "activity_monitor" role. See the Role resources for how to assign "activity_manager" and "activity_monitor" roles to identities or groups.

If the user does not have any "activity_manager" or "activity_monitor" roles, PermissionDenied will be returned by all advanced collection management resources.

1.1. Guest Collections and Manager Privileges

A user can have the "activity_manager" or "activity_monitor" roles on a collection or an endpoint. Having one of these two roles on an endpoint implicitly gives the corresponding role on all collections on that endpoint. Similarly having one of these roles on a mapped collection gives the corresponding role on all guest collections on that mapped collection.

Note

If the user has multiple effective roles on a collection, the highest privilege role will be used.

With few exceptions, a user with the "activity_manager" role on a guest collection cannot override a configuration change made by a user with the "activity_manager" role on the host mapped collection or endpoint. Activity managers have the following rules:

A user with the "activity_manager" role on an endpoint or mapped collection can create a pause rule on the mapped collection, which also affects all its guest collections. The pause rule will not be in the pause rule list of a user with the "activity_manager" role on a guest collection.
A user with the "activity_manager" role on the endpoint or mapped collection can also create a pause rule on a specific guest collection. In that case, the rule will be in the pause rule list of users with the "activity_manager" role on the guest collection, but they cannot edit or delete the rule.
A user with the "activity_manager" role on a guest collection can create a rule on the guest collection. A rule that was created by such a user can be updated or deleted by users with an effective "activity_manager" role on the guest collection.
Users with the "activity_manager" role on a collection can pause a task (per-task pause). The pause state is tracked separately depending on whether the user who initiated the pause had the "activity_manager" role on a parent or only on the collection itself. A user with the "activity_manager" role on a parent endpoint or collection can resume a per-task pause set by either type of user. However, a user with the "activity_manager" role only on a guest collection cannot resume a per-task pause set by a user with the "activity_manager" role on the endpoint or mapped collection.
A task to or from a guest collection can be canceled by a user with an effective "activity_manager" role on either the guest collection or a parent endpoint or mapped collection.

For more details, see the individual operation documentation below.

2. Document Types

2.1. Task Document

The task document includes all fields from the user facing task resources (see the Task Documentation), with the following additions:

2.1.1. Extra Fields

Also includes descriptions for fields that behave differently from their counterpart in the single user document returned by /task_list, notably source and destination collection fields which have different visibility rules.

Field Name	JSON Type	Description
source_endpoint^[1]	string	[DEPRECATED] Use `source_endpoint_id` instead.
source_endpoint_id^[1]	string	Id of the source collection. Visible if the collection is public or if the user has the "administrator" or "activity_monitor" role on the collection, otherwise it will be null.
source_endpoint_display_name^[1]	string	Display name of the source collection, same visibility rules as `source_endpoint_id`.
destination_endpoint^[1]	string	[DEPRECATED] Use `destination_endpoint_id` instead.
destination_endpoint_id^[1]	string	Id of the destination collection. Visible if the collection is public or if the user has the "administrator" or "activity_monitor" role on the collection, otherwise it will be null.
destination_endpoint_display_name^[1]	string	Display name of the destination collection, same visibility rules as `destination_endpoint_id`.
source_host_endpoint^[1]	string	[DEPRECATED] Use `source_host_endpoint_id` instead.
source_host_endpoint_id^[1]	string	If the source collection is a Globus Connect Server guest collection, this will be the id of the host mapped collection. If the source collection is a Globus Connect Personal guest collection, this will be the id of the endpoint. If the source collection is not a guest collection, this field will be null. Visible if the parent entity is public, or if the user has the "administrator" or "activity_monitor" effective role on the parent entity; otherwise it will be null.
source_host_endpoint_display_name^[1]	string	Display name of the `source_host_endpoint_id` if non null.
source_mapped_collection_id	string	UUID of the mapped collection hosting the source collection if it is a guest collection. Visible if the mapped collection is public, or if the user has the "administrator" or "activity_monitor" effective role on the source mapped collection; otherwise it will be null. Will also be null if the source collection is not a guest collection.
source_mapped_collection_display_name	string	Display name of `source_mapped_collection_id` if non null.
destination_host_endpoint^[1]	string	[DEPRECATED] Use `destination_host_endpoint_id` instead.
destination_host_endpoint_id^[1]	string	If the destination collection is a Globus Connect Server guest collection, this will be the id of the host mapped collection. If the destination collection is a Globus Connect Personal guest collection, this will be the id of the host endpoint. If the destination collection is not a guest collection, this field will be null. Visible if the parent entity is public, or if the user has the "administrator" or "activity_monitor" effective role on the parent entity; otherwise it will be null.
destination_host_endpoint_display_name^[1]	string	Display name of the `destination_host_endpoint_id` if non null.
destination_mapped_collection_id	string	UUID of the mapped collection hosting the destination collection if it is a guest collection. Visible if the mapped collection is public, or if the user has the "administrator" or "activity_monitor" effective role on the destination mapped collection; otherwise it will be null. Will also be null if the destination collection is not a guest collection.
destination_mapped_collection_display_name	string	Display name of `destination_mapped_collection_id` if non null.
source_host_path	string	If the source collection is a guest collection, the path it is hosted on on the mapped collection. Visible if the user has the "administrator" effective role on the source guest collection itself, or if the user has the "activity_monitor" effective role on its mapped collection; otherwise it will be null. Will also be null if the source collection is not a guest collection.
destination_host_path	string	If the destination collection is a guest collection, the path it is hosted on on the mapped collection. Visible if the user has the "administrator" effective role on the destination guest collection itself, or if the user has the "activity_monitor" effective role on its mapped collection; otherwise it will be null. Will also be null if the destination collection is not a guest collection. Always null for delete tasks, which don’t have a destination.
is_ok	boolean	For active tasks, this will be True if `nice_status` is either `OK` or `Queued`. Always null for completed tasks, which do not have `nice_status`.
source_local_user	string	The name of the local user that the Globus user mapped to on the source collection at the time the task was started. This will be "null" initially for all tasks until the information can be acquired. For Globus Connect Personal mapped collections, this will be the local user that the application was run as during setup. For guest collections, this will be the local user that was used when creating the guest collection and this field will be "null" unless the user has the "activity_monitor" effective role on the source host endpoint. For mapped collections, this will be the local user that was mapped to and this field will be "null" unless the user has the "activity_monitor" effective role on the source collection itself.
source_local_user_status	string	A status code indicating if the local user is available for the source collection, or the reason it’s not available. It can have any of the following values, and new values may be added in the future: "OK" The local user is set. "NO_PERMISSION" The user does not have the "activity_manager" or "activity_monitor" role on the collection (or for guest collections, the user does not have one of the two roles on a parent endpoint or mapped collection). "NOT_SCANNED" For active tasks, this indicates that the asynchronous process that fetches the local user has not completed. For complete tasks, this indicates that the task completed before this feature was added or cancelled before the local user could be fetched. "ENDPOINT_ERROR" An error occurred while contacting the collection to determine the local user. (This is a case of legacy endpoint terminology)
destination_local_user	string	Like `source_local_user` but for the destination collection. Always "null" for delete tasks, which don’t have a destination.
destination_local_user_status	string	Like `source_local_user_status`, but for the destination collection. In addition to the status codes described above, it will have the value "NO_ENDPOINT"^[1] for delete tasks.
owner_string	string	The Globus Auth identity username corresponding to the primary task owner (with id `owner_id`). This is provided as a convenience to clients, as something that can be displayed to end users (without having to call the Globus Auth API to get the identity details using `owner_id`).

2.2. Admin cancel document

The admin cancel document is used to request and track cancellation of one or more tasks by id.

Admin cancel document example

{
  "DATA_TYPE": "admin_cancel",
  "id": 985,
  "message": "Disk failure on GridFTP server",
  "task_id_list": [
    "041751b8-d6e3-4452-82a7-aa98200f4557",
    "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"
  ],
  "done": false
}

2.2.1. Admin cancel fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "admin_cancel" to indicate this document type.
message	string	Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported. Not included in create response or later GET responses.
id	string	Unique id of this bulk cancel request. This should not be set in create requests, and will be generated by the system and set in the create response.
done	boolean	"true" when all tasks in the list have been canceled or finished on their own, "false" otherwise. Returned in the create response and the status request, not used on in the create request body.
task_id_list	string list	List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large cancel requests. Note that the limit of 1000 is larger than the limit on the `filter_task_id` parameter on `task_list`.

2.3. Admin pause document

The admin pause document is used to request pause for one or more tasks by id. This is tracked separately from pause rules.

Admin pause document example

{
  "DATA_TYPE": "admin_pause",
  "message": "Scratch is getting full",
  "task_id_list": [
    "041751b8-d6e3-4452-82a7-aa98200f4557",
    "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"
  ]
}

2.3.1. Admin pause fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "admin_pause" to indicate this document type.
message	string	Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported.
task_id_list	string list	List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large pause requests.

2.4. Admin resume document

The admin resume document is used to request resume of one or more tasks by id.

Admin resume document example

{
  "task_id_list": [
    "041751b8-d6e3-4452-82a7-aa98200f4557",
    "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"
  ]
}

2.4.1. Admin resume fields

Field Name	JSON Type	Description
task_id_list	string list	List of task ids, maximum 1000. Note that the limit of 1000 is larger than the limit on the `filter_task_id` parameter on `task_list`.

2.5. Pause rule document

The pause rule document represents a rule that causes tasks and certain operation to be paused.

Uniqueness

Pause rule uniqueness is enforced on (endpoint_id, identity_id, created_by_host_manager). For guest collections, this means that for each pair of (endpoint_id, identity_id), there can be one pause rule created by a user with the "activity_manager" role on the host mapped collection or endpoint, and one created by a user with the "activity_manager" role on the guest collection itself. For other collection types, there can only be one such rule. Rules on the entire collection, i.e. with a null identity_id, are treated as a special value of identity_id regarding uniqueness, so there can be only one collection wide rule (or two on guest collections).

Pause rule document example

{
  "DATA_TYPE": "pause_rule",
  "created_by_host_manager": true,
  "editable": true,
  "endpoint": "u_eyljfjd6jfg67nm6zp6gly4qpu#e09c6728-80a0-11ee-bddb-c52a29481bea",
  "endpoint_display_name": "Globus Tutorial Collection 1",
  "endpoint_id": "6c54cade-bde5-45c1-bdea-f4bd71dba2cc",
  "id": "b55234ae-efb5-4373-9dc3-497f6a97c851",
  "identity_id": null,
  "message": "Quota exceeded, please delete data",
  "modified_by": "u_jr3525vktfcjblyz3sa2gewdue",
  "modified_by_id": "4c77dd76-aa99-4490-af19-dc81a312c3a1",
  "modified_time": "2024-01-04T17:09:45+00:00",
  "pause_ls": false,
  "pause_mkdir": true,
  "pause_rename": true,
  "pause_symlink": true,
  "pause_task_delete": false,
  "pause_task_transfer_read": true,
  "pause_task_transfer_write": false,
  "start_time": null,
  "user": null
}

2.5.1. Pause rule fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "pause_rule" to indicate this document type.
id	string	Unique id of this pause rule. This should not be set in create requests, and will be generated by the system and set in the create response.
message	string	Message to users as to why the tasks are being paused. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported.
start_time	ISO 8601 datetime string, null, or "now"	If null (the default value), pause existing tasks and all future tasks. If specified, only pause tasks created at or after the specified time. If the special string "now", exact case, is specified, uses the current time on the server at the time the request is received.
endpoint_id^[1]	string	Id of the collection to pause new tasks on. Required.
endpoint_display_name^[1]	string	Display name of the collection. This is an output only field, for convenience when displaying pause rules. Note that it may be null if the display name has not been set for the collection.
endpoint^[1]	string	[DEPRECATED] Use `endpoint_id` instead.
user	string	[DEPRECATED] Use `identity_id` instead. Username of a user to pause tasks for on the collection. If `identity_id` is set to an identity that has never been used in the Transfer service, then this will be null. This will also be null for rules that apply to all users on a collection, in which case `identity_id` will also be null.
identity_id	string	Identity id of an identity to pause tasks for on the collection, or null to indicate all identities on the collection. This will affect tasks with a matching `owner_id` or with a match in the set of linked identities at the time the task was submitted.
modified_time	ISO 8601 datetime string	Time the rule was created or last updated. This is set by the server on create and update and can’t be modified by clients.
modified_by	string	[DEPRECATED] Username of the user who last updated or created the pause rule. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. Use `modified_by_id` instead. If the modified by identity id is not a globus-id.org identity, this will be the same as the `modified_by_id`.
modified_by_id	string	Identity id of the identity that last updated or created the pause rule. If the collection in the rule is a guest collection, the user has the "activity_monitor" effective role on the guest collection and not a parent endpoint or mapped collection, and the rule has `created_by_host_manager` set to "true" or has been updated by a user with the "activity_manager" effective role on the parent endpoint or mapped collection, this field and `modified_by` will be set to "null". Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
created_by_host_manager	boolean	A rule on a guest collection created by a user with the "activity_manager" role on the guest collection and not a parent endpoint or mapped collection, will have this field set to false; in all other cases it will be true. This field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
editable	boolean	True if the current user has permission to update or delete the rule. See the pause rule operation documentation for details about authorization requirements and when this will be set. See pause rule list for details. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
pause_ls	boolean	Prevent API ls (directory listing) operations. Default "true".
pause_mkdir	boolean	Prevent API mkdir (create directory) operations. Default "true". Note that this only affects the API mkdir operation - if `pause_transfer_write` is "false", then directories can be created as part of the transfer operation.
pause_symlink	boolean	Prevent API symlink creation operations. Default "true". Note that this only affects the API symlink operation - if `pause_transfer_write` is "false", then symlinks can be created as part of the transfer operation.
pause_rename	boolean	Prevent API file and directory rename operations. Default 'true'.
pause_task_delete	boolean	Whether to pause matching tasks of type "DELETE". Default "true".
pause_task_transfer_write	boolean	Whether to pause matching tasks of type "TRANSFER" with the collection as destination.
pause_task_transfer_read	boolean	Whether to pause matching tasks of type "TRANSFER" with the collection as source.

3. Common Query Parameters

Name	Description
fields	Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed. For list document types (with `DATA_TYPE` ending in "_list"), this selects the fields of the item documents, not the top level paging and list meta data fields.

4. Common Errors

The error code can be found in the HTTP response body JSON document. See error overview .

Code	HTTP Status	Description
EndpointNotFound^[1]	404	If <collectipn_id> not found.
TaskNotFound	404	If the task specified by <task_id> is not found
PauseRuleNotFound	404	If the pause rule specified by <pause_rule_id> is not found
PermissionDenied	403	If user does not have the required role on one or more of the specified tasks, collections, or pause rules.
ServiceUnavailable	503	If the service is down for maintenance.

5. Path Arguments

The operations below make use of the following arguments in the URL path. In this documentation parameter names are denoted by < and >; these should not be included literally in the request path.

Name	Type	Description
collection_id	string	The `id` field of the collection.
task_id	string	Unique id string of a task.

6. Operations

6.1. Get tasks

Get a list of tasks involving the collections the user has the "activity_monitor" role on. All requests will implicitly filter based on the privileges of the user. The results can be sorted and filtered in different ways, and paging is required unless a filter to show only active tasks is used.

This resource uses last key paging.

Note

The name of the source and destination collections will be visible if the collection is public or if it’s owned by the current user. As a special case, if the collection is private and not owned by the current user (and would normally be hidden), but the current user has the "activity_monitor" role on a parent endpoint or mapped collection, then the name will be visible. This is the same as the visibility rules for /endpoint_manager/endpoint/<collection_id>. See the extra field descriptions above for visibility of the host name and path.

URL	/endpoint_manager/task_list^[1]
Method	GET
Response Body	List of Task documents. { "DATA_TYPE": "task_list", "limit": 10, "last_key": "123abc", "has_next_page": true, "DATA": [<task document> ...] }

6.1.1. Query Parameters

Query Parameter	Type	Default	Description
last_key	string	null	Opaque value representing the last element in the previous result set page, used to fetch the following page. This will return all results starting from but not including the last element of the previous page.
limit	int	100	Maximum number of results to return. The maximum allowed limit is 1000. If `filter_status` is a subset of ("ACTIVE", "INACTIVE"), `limit=0` is supported as a shortcut for `limit=1000`. It was originally designed to return all active tasks, but this was a mistake in the original design because the number of active tasks is not bounded. It’s unlikely we will have more than 1000 active tasks any time soon, but it’s not the kind of thing we want to risk. For this reason `limit=0` is deprecated, but for now the UX can safely assume that it will return all active tasks (which it will with very high probability, just not 100%).
filter_*	string	null	See filter documentation below.

6.1.2. Ordering

Tasks that are still in progress are always sorted by request_time descending (newest first). Completed tasks are sorted by completion_time descending. In progress tasks will be sorted before completed tasks.

6.1.3. Filters

Filter Syntax

Filters are passed as separate query parameters, of the form filter_FILTERNAME=FILTERVALUE. Many of the filters are named after a field they apply to, but a few are custom filters with more complex behavior.

If multiple filters are set in the request, only results matching all filters will be returned - there is an implicit logical AND between filters, unless otherwise specified. Within a single filter that accepts multiple values, there is typically an implicit OR. For example, specifying filter_task_id=123,456,678 will return tasks with id 123 OR 456 OR 678.

Filter values, like any other query parameter value, must be percent encoded. The query parameter names will always be safe to pass without further encoding, because they use a subset of characters that do not require encoding.

Task List Filters

All task list filters are subject to the user’s privileges. For example, filtering on user will only return tasks submitted by that user if they involve a collection the requesting user has the "activity_manager" or "activity_monitor" role on. Some requests will result in an error: specifying a task id filter for a task that does not involve a collection the user has an appropriate role on will result in a PermissionDenied error.

For any query that doesn’t specify a filter_status that is a subset of ("ACTIVE", "INACTIVE"), at least one of filter_task_id or filter_endpoint is required. This requirement is present because completed tasks are stored separately in a very large table and it is very expensive to query without making use of an index, which can be done only if an appropriate filter is present.

Query Parameter	Filter Type	Description
filter_status	equality list	Comma separated list of task statuses. Return only tasks with any of the specified statuses. Note that in-progress tasks will have status "ACTIVE" or "INACTIVE", and completed tasks will have status "SUCCEEDED" or "FAILED".
filter_task_id	equality list	Comma separated list of task_ids, limit 50. Return only tasks with any of the specified ids. If any of the specified tasks do not involve a collection the user has an appropriate role for, a `PermissionDenied` error will be returned. This filter can’t be combined with any other filter. If another filter is passed, a `BadRequest` will be returned.
filter_owner_id	equality	A Globus Auth identity id. Limit results to tasks submitted by the specified identity, or linked to the specified identity, at submit time. Returns `UserNotFound` if the identity does not exist or has never used the Globus Transfer service. If no tasks were submitted by this user to a collection the current user has an appropriate role on, an empty result set will be returned. Unless filtering for running tasks (i.e. `filter_status` is a subset of ("ACTIVE", "INACTIVE"), `filter_endpoint` is required when using `filter_owner_id`.
filter_username	equality	[DEPRECATED] Use `filter_owner_id` instead. A Globus username. The username is mapped to the globus identity id, and passed to `filter_owner_id`. Just like `filter_owner_id`, `filter_endpoint` is required unless filtering for running tasks. Returns `UserNotFound` if the user does not exist.
filter_endpoint^[1]	equality	Single endpoint or collection id. Return only tasks with a matching source or destination collection or matching source or destination host endpoint or collection.
filter_is_paused	boolean equality	Return only tasks with the specified `is_paused` value. Requires that `filter_status` is also passed and contains a subset of "ACTIVE" and "INACTIVE". Completed tasks always have `is_paused` equal to "false" and filtering on their paused state is not useful and not supported. Note that pausing is an async operation, and after a pause rule is inserted it will take time before the is_paused flag is set on all affected tasks. Tasks paused by id will have the `is_paused` flag set immediately.
filter_completion_time	datetime range	Start and end date-times separated by a comma. Each datetime should be specified as a string in ISO 8601 format: YYYY-MM-DDTHH:MM:SS, where the "T" separating date and time is literal, with optional \+/-HH:MM for timezone. If no timezone is specified, UTC is assumed, or a trailing "Z" can be specified to make UTC explicit. A space can be used between the date and time instead of a space. A blank string may be used for either the start or end (but not both) to indicate no limit on that side. Returns only complete tasks with `completion_time` in the specified range. If the end date is blank, it will also include all active tasks, since they will complete some time in the future.
filter_min_faults	int	Minimum number of cumulative faults, inclusive. Return only tasks with `faults >= N`, where N is the filter value. Use `filter_min_faults=1` to find all tasks with at least one fault. Note that many errors are not fatal and the task may still be successful even if `faults >= 1`. See the faults field documentation for details.
filter_local_user	equality	A valid username on the collection’s file system, as a utf8 encoded string. Requires that `filter_endpoint` is also set. Return only tasks that have successfully fetched the local user from the collection, and match the values of `filter_endpoint` and `filter_local_user` on the source or on the destination.
filter_endpoint_use^[1]	equality	Can be set to either `source` or `destination`. Available only when `filter_endpoint` is also supplied. Returns only tasks where the endpoint or collection was used in the specified capacity.

6.2. Get task

Get details of a single task by id. The result will include the task document and the extra task fields described above.

Authorization

Requires the "activity_monitor" effective role on a source or destination collection of the task. Note that if the user owns the task but does not have an appropriate role on a collection this will still return a "PermissionDenied" error.

URL	/endpoint_manager/task/<task_id>^[1]
Method	GET
Response Body	Task document.

6.3. Get task events

Get a list of events for a single task.

This resource uses offset paging.

See the event document documentation for details.

Authorization

URL	/endpoint_manager/task/<task_id>/event_list^[1]
Method	GET
Response Body	List of event documents

6.3.1. Query Parameters

Query Parameter	Type	Default	Description
offset	int	0	Return results starting from this offset within the total result set. Note that for active tasks this results set will be changing, and as the result set changes so will the meaning of the offset. For this reason, paging through events on active tasks may return unexpected results.
limit	int	100	Maximum number of results to return. The maximum allowed limit is 1000.
filter_*	string	null	See filter documentation below.

6.3.2. Ordering

Results are sorted by time descending (newest first).

6.3.3. Filters

Query Parameter	Filter Type	Description
filter_is_error	flag	1 for True. Return only events that are errors. The inverted form (returning only non-errors) is not supported. By default all events are returned.

6.4. Get task pause info

This operation returns the same information as the normal user get task pause info operation, but has different authorization requirements. Note that pause_rule_limited documents are still returned instead of the full pause_rule, since the result can include pause rules for collections the current user does not have an "activity_monitor" role on.

Authorization

URL	/endpoint_manager/task/<task_id>/pause_info^[1]
Method	GET
Response Body	{ "DATA_TYPE": "pause_info_limited", "pause_rules": [... list of pause_rule_limited documents...], "source_pause_message": null, "destination_pause_message": "Disk problems, pausing all tasks until we resolve", "source_pause_message_share": null, "destination_pause_message_share": null }

URL

/endpoint_manager/task/<task_id>/pause_info^[1]

Method

GET

Response Body

{
    "DATA_TYPE": "pause_info_limited",
    "pause_rules": [... list of pause_rule_limited documents...],
    "source_pause_message": null,
    "destination_pause_message": "Disk problems, pausing all tasks until we resolve",
    "source_pause_message_share": null,
    "destination_pause_message_share": null
}

6.5. Get task successful transfers

For a "TRANSFER" type task, get a list of files transferred successfully, after a task is complete (with status "FAILED" or "SUCCEEDED"), as a collection activity monitor. See Get task successful transfers (as normal user) for details. If the current user has the "activity_monitor" role on only one of the collections, the paths corresponding to the other collection will be "null".

This resource uses marker paging.

Authorization

URL	/endpoint_manager/task/<task_id>/successful_transfers [?marker=MARKER]^[1]
Method	GET
Response Body	`{ "DATA_TYPE": "successful_transfers", "marker": 0, "next_marker": 93979, "DATA": [ { "DATA_TYPE": "successful_transfer", "checksum": "c7059bb19433cc3cabaa6236c83d56668a843dd2", "checksum_algorithm": "SHA1", "destination_path": "/path/to/destination", "dynamic": false, "size": 4, "source_path": "/path/to/source" } ] }`

URL

/endpoint_manager/task/<task_id>/successful_transfers [?marker=MARKER]^[1]

Method

GET

Response Body

{
  "DATA_TYPE": "successful_transfers",
  "marker": 0,
  "next_marker": 93979,
  "DATA": [
    {
      "DATA_TYPE": "successful_transfer",
      "checksum": "c7059bb19433cc3cabaa6236c83d56668a843dd2",
      "checksum_algorithm": "SHA1",
      "destination_path": "/path/to/destination",
      "dynamic": false,
      "size": 4,
      "source_path": "/path/to/source"
    }
  ]
}

6.6. Get task skipped errors transfers

For "TRANSFER" tasks that are completed (have status "SUCCEEDED" or "FAILED"), get a list of paths that were skipped due to the skip_source_errors flag being set to true. The list will contain information about the error and the item that was skipped. See Get task skipped errors (as normal user) for details. If the current user has the "activity_monitor" role on only one of the collections, the paths and error details corresponding to the other collection will be redacted.

This resource uses marker paging.

Authorization

URL	/endpoint_manager/task/<task_id>/skipped_errors [?marker=MARKER]^[1]
Method	GET
Response Body	{ "DATA_TYPE": "skipped_errors", "marker": 0, "next_marker": null, "DATA": [ { "DATA_TYPE": "skipped_error", "checksum_algorithm": null, "destination_path": "/~/file4.txt", "error_code": "FILE_NOT_FOUND", "error_details": "550-GlobusError: v=1 c=PATH_NOT_FOUND%0D%0A550-GridFTP-Errno: 2%0D%0A550-GridFTP-Reason: System error in lstat%0D%0A550-GridFTP-Error-String: No such file or directory%0D%0A550 End.%0D%0A", "external_checksum": null, "is_directory": false, "is_symlink": false, "source_path": "/share/godata/file4.txt" } ] }

URL

/endpoint_manager/task/<task_id>/skipped_errors [?marker=MARKER]^[1]

Method

GET

Response Body

{
  "DATA_TYPE": "skipped_errors",
  "marker": 0,
  "next_marker": null,
  "DATA": [
    {
      "DATA_TYPE": "skipped_error",
      "checksum_algorithm": null,
      "destination_path": "/~/file4.txt",
      "error_code": "FILE_NOT_FOUND",
      "error_details": "550-GlobusError: v=1 c=PATH_NOT_FOUND%0D%0A550-GridFTP-Errno: 2%0D%0A550-GridFTP-Reason: System error in lstat%0D%0A550-GridFTP-Error-String: No such file or directory%0D%0A550 End.%0D%0A",
      "external_checksum": null,
      "is_directory": false,
      "is_symlink": false,
      "source_path": "/share/godata/file4.txt"
    }
  ]
}

6.7. Get endpoint or collection

Get details of an endpoint or collection. This resource is similar to standard get endpoint or collection by id, and has the same authorization requirements. The one difference is that the in_use field is always set to "null".

See the endpoint or collection document documentation for details.

Authorization

Requires that the endpoint be public, or that the user has an "administrator", "restricted_administrator", or "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_or_collection_id>^[1]
Method	GET
Response Body	Endpoint or collection document.

6.8. Get hosted collection list

Get a list of guest collections hosted on a specified endpoint or mapped collection. The response contains full collection documents, with the same differences from the standard collection document as Get endpoint or collection.

This resource uses offset paging, and includes a has_next_page boolean in the response body.

Authorization

Requires the "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_or_collection_id>/hosted_endpoint_list^[1]
Method	GET
Response Body	{ "DATA_TYPE": "endpoint_list", "offset": 0, "limit": 1000, "has_next_page": false, "DATA": [ { "DATA_TYPE": "endpoint", "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258", "owner_string": "bob@globusid.org", "display_name": "Project1 Guest", ... } ] }

URL

/endpoint_manager/endpoint/<endpoint_or_collection_id>/hosted_endpoint_list^[1]

Method

GET

Response Body

{
    "DATA_TYPE": "endpoint_list",
    "offset": 0,
    "limit": 1000,
    "has_next_page": false,
    "DATA": [
        {
            "DATA_TYPE": "endpoint",
            "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258",
            "owner_string": "bob@globusid.org",
            "display_name": "Project1 Guest",
            ...
        }
    ]
}

6.8.1. Query Parameters

Query Parameter	Type	Default	Description
limit	int	1000	Maximum number of results to return. 1000 is both the default and maximum.
offset	int	0	Return results starting from this offset within the total result set.

6.8.2. Ordering

Results are ordered by display_name.

6.8.3. Filtering

No filtering options are supported at this time.

6.9. Get guest collection permission list

Get a list of permissions on the specified guest collection. Returns the same access_list document as the standard permission list resource, but has different authorization requirements.

Authorization

Requires the "activity_monitor" effective role on the guest collection.

URL	/endpoint_manager/endpoint/<collection_id>/access_list^[1]
Method	GET
Response Body	"access_list" document

6.10. Get monitored endpoints and collections

Get a list of the endpoints and collections the current users has explicit monitor or manager role on. Like all manager resources, a 403 response with a "PermissionDenied" error code body will be returned if the user has no permissions. The standard my_effective_roles field can be used to determine which roles the user has.

Note

If the user has the "activity_manager" or "activity_monitor" role on a parent endpoint or mapped collection, they implicitly have the corresponding role on all child collections under it, but this list will not necessarily include any of those collections. Collections will only be in this list if the user has been explicitly granted one of the roles on the collection itself. If the user has an explicit role on both a collection and one of its parents, both will be in the list.

The response contains full endpoint or collection documents, with the same differences from the standard endpoint or collection document as <get_endpoint_or_collection,Get endpoint or collection>>.

URL	/endpoint_manager/monitored_endpoints^[1]
Method	GET
Response Body	{ "DATA_TYPE": "monitored_endpoints", "DATA": [ { "DATA_TYPE": "monitored_endpoint", "id": "196b3545-0878-4443-a1e6-57eb833beb06", "my_effective_roles": ["activity_manager"], "display_name": "Great Endpoint", ... }, ... ] }

URL

/endpoint_manager/monitored_endpoints^[1]

Method

GET

Response Body

{
    "DATA_TYPE": "monitored_endpoints",
    "DATA": [
        {
            "DATA_TYPE": "monitored_endpoint",
            "id": "196b3545-0878-4443-a1e6-57eb833beb06",
            "my_effective_roles": ["activity_manager"],
            "display_name": "Great Endpoint",
            ...
        },
        ...
    ]
}

6.10.1. Ordering

Results are ordered by display_name.

6.11. Cancel tasks

Cancel one or more tasks by task id as an activity manager. If a task is already complete or canceled at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.

Task owners will be notified via email that their task(s) were canceled by an activity manager. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.

Note

Activity manager cancel requests still involve processing each task individually, so it’s possible that some tasks will succeed before the cancel request is processed, and others will get canceled by this request or even a concurrent cancel request. The done field indicates when all tasks in the request have status "FAILED" or "SUCCEEDED" and are no longer running.

Authorization

Requires the "activity_manager" effective role on the source or destination collection of each task in the request. If this check fails for any of the tasks, the entire request will fail with a "PermissionDenied" error.

URL	/endpoint_manager/admin_cancel^[1]
Method	POST
Request Body	Admin cancel document with `task_id_list` and `message` fields.
Response Body	Admin cancel document with `id` and `done` fields.

6.12. Get cancel status by id

Returns an admin_cancel document without the task_id_list; clients can check the done field to determine if the cancel request is complete.

Authorization

Only the user who submitted the original cancel request is guaranteed to be able to get its status.

Note

In the current implementation, all completed request IDs and all request IDs never before seen are returned as "done". Clients should not rely on this behavior, and take care not to corrupt the ID.

URL	/endpoint_manager/admin_cancel/<admin_cancel_id>
Method	GET
Response Body	Admin cancel document with `id` and `done` fields.

6.13. Pause tasks

Pause one or more tasks by task id as an activity manager. If a task is already complete or paused at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.

Per-task pause is tracked separately for endpoint or mapped collection activity managers and guest collection activity managers. A task is paused if either has been set, and will only resume when both are cleared. An endpoint or mapped collection activity manager can clear both when resuming, while a guest collection activity manager can only clear a pause set by other guest collection activity managers.

Task owners will be notified via email that their task(s) were paused by an activity manager. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.

Note

Activity manager pause requests are asynchronous, and it’s possible that some tasks will succeed before the pause request is processed.

Authorization

URL	/endpoint_manager/admin_pause^[1]
Method	POST
Request Body	'admin_pause' document
Response Body	'result' document with code "PauseAccepted"

6.14. Resume tasks

Resuming a task involves removing all per-task pauses on the task, and overriding existing pause rules (host and share, source and destination) that affect the task. This operation removes and overrides pause on whichever collections the current user has the "activity_manager" role on.

As an example, suppose a task involving a guest collection has been paused by two different users, one with the "activity_manager" role on the endpoint, and one with the "activity_manager" role on a child guest collection. A user with the "activity_manager" role on the endpoint can clear both per-task pause flags and set an override on all pause rules that might affect the task, so the task will resume. A user with the "activity_manager" role on the guest collection and not its endpoint can only clear one of the per-task pause flags; a resume operation submitted by such a user will still be considered successful, but the task won’t actually start running again until a user with the "activity_manager" role on the endpoint or mapped collection clears the other per-task pause flag.

This applies to source and destination collections as well, i.e. if a user has the "activity_manager" role on the source but not the destination, a resume operation will clear per-task pause and override pause rules on the source but not the destination.

To resume all tasks affected by a pause_rule, use Delete pause rule by id.

This API call will not raise an error if the task is already running and no per-task pause exists - it will simply set the pause rule override timestamp for the task to the specified value.

If there are no other pauses on the task, the task will resume. Otherwise it will only resume once an "activity_manager" of the other collection removes the remaining pauses. When the task actually begins running again, a resume email will be sent to the user. Just like pause, this is an asynchronous process.

Authorization

URL	/endpoint_manager/admin_resume^[1]
Method	POST
Request Body	'admin_resume' document
Response Body	'result' document with code "ResumeAccepted"

6.15. Get pause rules

Get a list of pause rules on collections that the current user has the "activity_monitor" role on.

Pause rules will be editable (the editable field will be "true") if one of the following conditions are met:

The collection is a mapped collection, and the current user has the "activity_manager" effective role on the mapped collection
The collection is a guest collection, the current user has the "activity_manager" effective role on the guest collection, and the rule was not created by a user with the "activity_manager" effective role on the endpoint or mapped collection. Note that rules created by a guest collection manager and later modified by a endpoint or mapped collection manager are NOT protected from further editing by a guest collection manager.
The collection is a guest collection, and the current user has the "activity_manager" effective role on the endpoint or mapped collection

If the result set contains over 1000 rules, a "LimitExceeded" error will be returned and the client must pass the filter_endpoint query parameter (with the collection id) to get the rules one collection at a time.

Authorization

Returns rules on collections for which the user has the "activity_monitor" effective role. If filter_endpoint or filter_host_endpoint is specified, the user must have the "activity_monitor" effective role on the specified collection.

Note

Pause rules are also accessible to normal users via the Get collection pause rules resource.

URL	/endpoint_manager/pause_rule_list [?filter_endpoint=COLLECTION_ID]^[1]
Method	GET
Response Body	Pause rule list document.

6.15.1. Pause Rule Filtering

Query Parameter	Filter Type	Description
filter_endpoint^[1]	string equality	Single collection id. Include only pause rules on the specified collection.
filter_host_endpoint^[1]	string equality	Single endpoint or mapped collection id. Include only pause rules on guest collections hosted by the specified endpoint or collection.

6.16. Create pause rule

Create a new pause rule. New tasks matching the rule will be paused immediately. If start_time is not set, any existing tasks that match will be paused asynchronously. If set, only tasks submitted after the specified time will be paused.

If the appropriate flags are set, the rule will also prevent foreground operations for ls, mkdir, and rename. Clients requesting these operation on the specified collection and matching the user clause will receive an OperationPaused error containing the pause message (or the most specific pause message if multiple pause messages are in effect).

Authorization

Requires the "activity_manager" effective role on the collection in the rule.

URL	/endpoint_manager/pause_rule^[1]
Method	POST
Request Body	Pause rule document without `id` field.
Response Body	Pause rule document with server generated `id` field added.

6.17. Get pause rule

Get a pause rule by id.

Authorization

Requires the "activity_monitor" effective role on the collection in the rule.

URL	/endpoint_manager/pause_rule/<pause_rule_id>^[1]
Method	GET
Response Body	Pause rule document

6.18. Update pause rule

Update a pause rule by id. Only the start_time, message, and pause type fields (with the pause_ prefix) can be updated. It is recommended that clients include only the fields to be updated in the request. If non-updatable fields are included, they will be ignored.

The modified_time and modified_by_id fields will be updated based on the time of the request and the user updating the rule. The response will contain these updated fields. Any manual task resume requests made in the past that overrode this pause rule will no longer be in effect, and such tasks will become paused.

Authorization

The rule must be marked editable in the pause rule list, see link for details.

URL	/endpoint_manager/pause_rule/<pause_rule_id>^[1]
Method	PUT
Request Body	Partial pause rule document (containing fields to be updated).
Response Body	Pause rule document

6.19. Delete pause rule

Delete an existing pause rule by id. Any tasks that were paused by this rule and are not affected by any other rule or per-task pause will resume.

Authorization

The rule must be marked editable in the pause rule list, see link for details.

URL	/endpoint_manager/pause_rule/<pause_rule_id>^[1]
Method	DELETE
Response Body	Result document.

1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections